ApplyThemeBackground

ApplyThemeBackground
Header:	Appearance.h		Carbon status:	Supported

Sets the background color or pattern of the current port to be consistent with that of an embedding object.

OSStatus ApplyThemeBackground (
    ThemeBackgroundKind inKind, 
    const Rect *bounds, 
    ThemeDrawState inState, 
    SInt16 inDepth, 
    Boolean inColorDev
);

inKind: A value of type ThemeBackgroundKind. Pass a constant specifying the type of embedding object. See “Theme Background Kind Constants” for descriptions of possible values.
bounds: A pointer to a structure of type Rect. Before calling ApplyThemeBackground, set the rectangle to a size and position that contains the embedding object, in local coordinates.
inState: A value of type ThemeDrawState. Pass a constant specifying the current state of the embedding object. See “Theme Draw State Constants” for descriptions of possible values.
inDepth: A signed 16-bit integer. Pass a value specifying the bit depth (in bits per pixel) of the current graphics port.
inColorDev: A value of type Boolean. Pass true to indicate that you are drawing on a color device, or false for a monochrome device.

function result: A result code.

DISCUSSION

The ApplyThemeBackground function sets the background color or pattern of the current port to match the background of an embedding object, such as a placard or tab control. Your application should call ApplyThemeBackground before erasing the background of your application’s content to ensure that the content background matches that of the object in which it is visually embedded.

ApplyThemeBackground aligns patterns based on the rectangle passed in the bounds parameter. This is in contrast to the function SetThemeBackground, which aligns patterns based on the origin of the current port.

You do not need to call ApplyThemeBackground if your content is an embedded part within a control hierarchy and is logically as well as visually embedded in its container; in this case, the Control Manager automatically requests the embedding control to set up the background before drawing the embedded control.

If you have a custom control definition function that erases its background before drawing, you should use the Control Manager function SetUpControlBackground before erasing. SetUpControlBackground calls ApplyThemeBackground if necessary.

VERSION NOTES

This function is available with Appearance Manager 1.1 and later.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.